home *** CD-ROM | disk | FTP | other *** search
/ MACD 5 / MACD 5.bin / workbench / tools / czesc_3 / pickfile / pickfile.doc < prev    next >
Text File  |  1998-01-01  |  14KB  |  384 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.                             Documentation
  7.  
  8.  
  9.  
  10.  
  11.                       PickFile Version 1.2 FreeWare
  12.  
  13.  
  14.  
  15.  
  16.                           @ 1992/93 by H.P.G
  17.  
  18.  
  19.  
  20.  
  21.  
  22.  
  23. Index:
  24. ======
  25.  
  26.  
  27.         Index
  28.         What is PickFile ?
  29.         System Requirements
  30.         Legal stuff
  31.         PickFile Start Options
  32.         Examples
  33.         Technical
  34.         At Last
  35.         Addresse
  36.         List Of Files
  37.  
  38.  
  39.  
  40.  
  41. What is PickFile ?:
  42. ===================
  43.  
  44.  
  45.         Under OS 2.xx it is now possible to use different sets of fonts,
  46.         patters and mouse pointers and to change them in a very easy
  47.         manner.
  48.  
  49.         Since I use this new system, I feel very happy if I use well
  50.         designed wbench pattern or window pattern or different overscan
  51.         sizes or different sets of fonts for my wbenchscreen.
  52.  
  53.         But if I have used e.g. a window pattern for a longer time, I
  54.         usually want to change this pattern.
  55.  
  56.         So first I have to start the WBPattern program which is located
  57.         in the `sys:prefs/` drawer ...
  58.  
  59.         After designing a new pattern, I have to save it as default.
  60.         After some time of using this pattern the whole procedure starts
  61.         again and again and not only for patterns than also for fonts
  62.         colours etc..
  63.  
  64.         PickFile can help you.
  65.         PickFile chose randomly an entry out of a list or optionally
  66.         a file out of a drawer. Then PickFile executes this file or
  67.         an optional commandline which must be supplied.
  68.  
  69.         PickFile has a variety of applications and is useful for
  70.         starting all kinds of files and programs.
  71.         PickFile (PF) is not only able to chose a file, but also
  72.         to execute a whole commandline which has to be supplied.
  73.  
  74.         You can also ask PF to chose more than one entry by one call.
  75.         To write about all possible kinds of aplications you may use
  76.         PF for, I haven`t the time and imagination here.
  77.  
  78.         You can use PF for calling prefs files or to start sampled
  79.         sounds (randomly) or just to create a slideshow with a randomly
  80.         order of your pictures...
  81.  
  82.         I have also include an example in the examples drawer.
  83.         I have also included some examples in this document.
  84.         (See Tutorial).
  85.  
  86.  
  87.  
  88. System Requirements:
  89. ====================
  90.  
  91.         PickFile needs kickstart 2.04 version 37L or better to run.
  92.         Under version 36L (1.4) or 1.3 it is not able to run, because
  93.         of the usage of some OS 2.xx only features for pattern matching
  94.         and commandline editing.
  95.         (Sorry).
  96.  
  97.  
  98. Legal Stuff:
  99. ============
  100.  
  101.         This  program  and  all files come with it, also the docfiles, are
  102.         released as FREEWARE.
  103.  
  104.         this means:
  105.  
  106.             everybody may use PickFile,
  107.  
  108.             everybody may copy PickFile, if:
  109.  
  110.                 1. You copy all included files, see list at the end of the
  111.                    doc file.
  112.                 2. No changes are made,  this  means  the  program and all
  113.                    included files must stay in the original form.
  114.                    Exception: you  may  archieve  it; but in this case you
  115.                               must also archieve the whole package.
  116.                 3. If  you  recompile  it, you have to include a notice to
  117.                    the original author. If you also want to (re)distribute
  118.                    in any new form you have to send me a copy.
  119.                 4. You may not sell PickFile.
  120.                    Execption: you`re  allowed  to  take  a  small copy fee
  121.                               which should not extend 5US$.
  122.                 5. If you want to include PickFile
  123.                    or one of the  included files as a part of a commercial
  124.                    package,  you  must  have  written  permission  of  the
  125.                    author (address see below).
  126.  
  127.  
  128.         I take no warranty or guaranty for the function of this program.
  129.         The whole risk of using PickFile stays only by the user.
  130.  
  131.  
  132.  
  133.  
  134.  
  135. PickFile Startoptions:
  136. ======================
  137.  
  138.  If you start PF from WBench, you will get only a short helptext.
  139.  If you instead call PF from CLI, so it uses the following
  140.  
  141.     Syntax: [File=F/K][Dir=D/K][MinVal=M/N][MaxVal=X/N][Test=T/K]
  142.             [Quiet=Q/K][Help=H/S][Cmd=C/F]
  143.  
  144.     File=F/K   :   If you specify file, than this file is read by PF.
  145.                    One line of this file will be randomly chosen. The
  146.                    given commandline will be used, if supplied one
  147.                    (see later Cmd). The File will be loaded in memory
  148.                    and then processed. This saves a lot of time.
  149.                    The syntax of this file will be described below.
  150.                    See also the examples section.
  151.  
  152.     Dir=D/K,   :   If you instead specify Dir no file will be processed
  153.                    but this dir is examined and a file of this dir
  154.                    will be randomly chosen. If given, a commandline
  155.                    will be used. (see later under Cmd). If you omit
  156.                    this commandline the chosen file will be started
  157.                    as an cli program.
  158.  
  159.     Pat=P/K    :   After Pat you can specify a pattern after AmigaDOS
  160.                    conventions. So only matched files will be processed
  161.                    and the selection can only be one of the matched
  162.                    files. The pat option will only be used if you use
  163.                    the dir option, otherwise this option will be ignored.
  164.  
  165.     MaxVal=X/N :   Here you can specify the number of entries which
  166.                    should be chosen by PickFile. The maximum value depents
  167.                    on the number of lines by use the file options or the
  168.                    number of files when using the dir option. If you specify
  169.                    a larger number the maximum available value will be used.
  170.                    Default: 1
  171.  
  172.     Test=T/S   :   If you use Test, the given commandline or the
  173.                    chosen file will not be executed but displayed in
  174.                    the cli window. This means you can use this option
  175.                    to see which commandline would be executed when run
  176.                    PickFile without the Test option.
  177.                    (Great for testing and debugging settings).
  178.  
  179.     Quiet=Q/S  :   If you use instead the Quiet option, PF doesn`t
  180.                    tell you which selection is done and which command
  181.                    is executed. Usually PF informs the user about the
  182.                    commandline which is currently executed. If you want
  183.                    to call PF e.g. in your startup-sequence to select
  184.                    a set of patterns, then the output of PF would opened
  185.                    the shell window. If this option is used the window
  186.                    still stays closed.
  187.                    (see also AmigaDOS manual Shell-Flag (AUTO)).
  188.                    This option is also useful for batch files which
  189.                    should not print any output to a shell window.
  190.                    Default: OFF.
  191.  
  192.     Help=H/S   :   If you use Help or the commandline contains any error
  193.                    a short helptext will be printed out.
  194.  
  195.     Cmd=C/F    :   This is the most powerful option. After the Cmd
  196.                    keyword you can specify a whole command line with all
  197.                    kinds of arguments. This commandline will then be
  198.                    called after chosing an entry. This option is
  199.                    available under file and dir option.
  200.                    The commandline may be embedded in "",s but this is
  201.                    optional.
  202.                    But if you use another shell than the standard shell
  203.                    e.g. CShell, I will recomment, to do this to prevent
  204.                    pattern expandings before calling the commandline.
  205.  
  206.                    All included []`s will be automatically replaced with
  207.                    the chosen entry. If you specify multiples selections
  208.                    this commandline will be called again for each entry.
  209.                    (see also MaxValue).
  210.                    So you can use PickFile also for recursion calls
  211.                    (BE VERY CAREFULL)
  212.  
  213.     For all options: you may use all options in any order.
  214.  
  215.     Exception: Cmd must be the last argument.
  216.  
  217.     All options are optional (what a surprise :-). But also here exists
  218.     one exeption:
  219.  
  220.     You must either specify a file or a dir.
  221.     If you specify a file and a dir the file will be processed and the
  222.     dir ignored.
  223.  
  224.     The syntax for the file must follow this conventions:
  225.  
  226.     The file must be 100% ascii code. There must not exists any kind
  227.     of comments, because, to handle this, would slow down the program
  228.     too much.
  229.  
  230.     Each line represents a command line. If you also supply a command
  231.     line (Cmd option), PF thinks it should pickup one or more lines
  232.     of the file and replace the given []`s of the command line.
  233.     So you see there should be no leading spaces in the lines.
  234.  
  235.  
  236. Examples:
  237. =========
  238.  
  239.             Now there are some example callings and commandline
  240.             options and their use.
  241.  
  242.  
  243.  
  244.     1. Example: lottery program
  245.     ---------------------------
  246.  
  247.       This example is included in the examples drawer.
  248.  
  249.       Assuming you have a file calling `Lotto.dat` in the current
  250.       directory which includes all numbers from 1 to 49 one number
  251.       in each line.
  252.       Assuming we want to chose 6 numbers randomly from 49 and we
  253.       want to print out the selections you can use the following
  254.       example commandline
  255.  
  256.  
  257.       PickFile F Lotto.dat X 6 C "echo [] > PRT:"
  258.                |           |   |
  259.                |           |   ---> This command line will be executed for
  260.                |           |        each chosen number.
  261.                |           |
  262.                |            ------> This tells PF to chose 6 different
  263.                |                    numbers out of the file
  264.                |
  265.                 ------------------> This is the file which cointains
  266.                                     the used numbers
  267.  
  268.  
  269.     2. Example: Randomly using of wbpattern set
  270.     -------------------------------------------
  271.  
  272.      Assuming we have several wbprefs patterns located in the
  273.      sys:prefs/presets drawer (these can be designed with the
  274.      WBPattern program and be saved with the menuitem Save As).
  275.      Assuming these wbpattern sets are called `wb.1.pat`,
  276.      `wb.2.pat` ... `wb.n.pat`. If you now insert the following
  277.      line into you startup-sequence:
  278.  
  279.      .....
  280.  
  281.      PickFile D Sys:Prefs/Presets/ P "wb.#?.pat" Q C
  282.          "Copy [] env:sys/wbpat"
  283.      .....
  284.      Endcli >NIL:
  285.  
  286.      ,so PickFile randomly picks up a set of these patterns each time you
  287.      boot up. To process only the wb.##.pat files, we have to specify here
  288.      Pat with the pattern 'wb.#?.pat' (for pattern matching see also
  289.      AmigaDOS manual). With Q (for Quiet) no outputs will be sent to the
  290.      shell window, so the AUTO boot shell window will not be opened.
  291.  
  292.      The commandline `Copy [] env:sys/wb.pat` will be replaced with
  293.      e.g. (Assuming PF had chosen wp.1.pat).
  294.  
  295.            ====>  Copy wb.1.pat env:sys/wb.pat
  296.  
  297.      After calling the IPrefs program in your startup-sequence this pattern
  298.      file is used for the wbpattern (really good ?).
  299.  
  300.      You can use this example also to change other environments like i.e.
  301.      screen sizes (NTSC-PAL or InterLaced/NON-Interlaced mode etc...)
  302.      (this functions also later at any time). You must therefor only change
  303.      the Pat and Cmd line patterns.
  304.  
  305.  
  306.     3. Example: Slideshow with several pictures in a randomly order
  307.     ---------------------------------------------------------------
  308.  
  309.      Assuming we have a disk with the name `PICTURES:` and this disk
  310.      contains 20 different picturs. So we simply can use the following
  311.      example call to PickFile to create a full slideshow and starts it.
  312.      I assume also that you have a picture viewer in the C: directory
  313.      which is called Show.
  314.  
  315.      PickFile D Pictures: X 20 Q C "C:Show []"
  316.  
  317.      All 20 pictures will now be displayed in a randomly generated order.
  318.      No outputs will be sent to the cli window. For each picture the
  319.      commandline `C:Show []` with the chosen picture name instead of the
  320.      []`s will be executed. I assume that C:Show can display the given
  321.      picture when specified at start time.
  322.  
  323.      There is an endless list of other applications which can be used
  324.      with PickFile.
  325.      If you know any other interesting application please let me know.
  326.  
  327.  
  328. Technical:
  329. ==========
  330.  
  331.     I spoke in this manual often about randomly selections. The
  332.     random generator routine is created by using the system time
  333.     (micros) to initialize the ran() routine. The selection is
  334.     then performed by calling sran().
  335.  
  336.     If you use multiple selections, I take care that each entry is
  337.     chosen only once. Also if you specify more entries in a list or
  338.     files that exists, only the correct number of entries will be
  339.     used.
  340.  
  341.     To prevent errors in command line execution, the selection of
  342.     drawers is not supported, they will be only ignored (certainly
  343.     except in path specifications).
  344.  
  345.  
  346. At Last:
  347. ========
  348.  
  349.     I hope (really) that there are some people out there which
  350.     are interested in this wonderful tool and stays here as your
  351.  
  352.  
  353.         H.P.G
  354.  
  355.  
  356. Addresse:
  357. =========
  358.  
  359.     Hans-Peter Guenther
  360.     Gruener Weg 5
  361.     3501 Fuldatal 2
  362.     W-Germany
  363.  
  364.  
  365. List Of Files:
  366. ==============
  367.  
  368.  (If you miss one or more of the following files your release is incomplete)
  369.  
  370.  
  371.     PickFile                : The binary
  372.     PickFile.info
  373.     PickFile.doc            : English manual
  374.     PickFile.doc.info
  375.     PickFile.dok            : German manual
  376.     PickFile.dok.info
  377.     Examples    (dir)
  378.     Examples
  379.         Lotto.dat           : Lottery file (Example 1)
  380.         Lotto.dat.info
  381.  
  382.  
  383. ----END
  384.